Inside Macintosh: QuickDraw GX Objects /

Chapter 5 - Ink Objects / Ink Objects Reference

Functions / Getting and Setting an Ink's Color

GXSetShapeColor

You can use the GXSetShapeColor function to assign a color to the ink object associated with a shape.

void GXSetShapeColor(gxShape target, const gxColor *data);

target

A reference to the shape whose ink object you want to assign the color to.

data

A pointer to a color structure containing the color to assign to the shape's ink object.

DESCRIPTION

The GXSetShapeColor function assigns the color pointed to by the data parameter to the ink object associated with the shape referenced in the target parameter.

Calling this function is almost equivalent to

GXSetInkColor(GXGetShapeInk(myShape),theColor);

except that, if the source shape's ink object is shared with other shapes, GXSetShapeColor creates a new copy of that ink object and attaches it to the source shape before changing its color. That way, calling this function does not produce any side effects on other shapes.

If the color pointed to by the data parameter references a color set or color profile object, QuickDraw GX increases the owner count of the referenced object.

SPECIAL CONSIDERATIONS

If you use this function to try to assign a color to a bitmap shape, the function posts an illegal_type_for_shape error. If the color space of the color pointed to by the data parameter is gxNoSpace, the function posts a colorSpace_out_of_range error.

ERRORS, WARNINGS, AND NOTICES

Errors
out_of_memory
shape_is_nil
color_is_nil
colorSpace_out_of_range	(debugging version)
colorSet_access_restricted	(debugging version)
colorProfile_access_restricted	(debugging version)
illegal_type_for_shape	(debugging version)
Notices (debugging version)
color_already_set
color_is_nil

SEE ALSO

To examine the color of the ink object associated with a shape, use the GXGetShapeColor function, described in the previous section.

To assign a color to an ink object directly, use the GXSetInkColor function, described on page 5-69.

Ink colors are introduced in the section "Color" beginning on page 5-7, and described fully in the chapter "Colors and Color-Related Objects" in this book. Assigning colors to bitmaps is discussed in the bitmap shapes chapter of Inside Macintosh: QuickDraw GX Graphics.

The GXGetShapeInk function is described in the chapter "Shape Objects" in this book.